.\" runuid.8
.\" wcm, 2009.12.11 - 2012.01.04
.\" ===
.TH runuid 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runuid \- run a program with specific user and group permissions
.SH SYNOPSIS
.B runuid [\-hV] [\-g
.I group
.B ] [\-s | \-S
.I grplist
.B ]
.I account program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runuid
runs
.I program
with the uid and gid set according to the user and group ID of
.IR account .
.PP
If
.I program
does not contain a ``/'' slash character,
.B runuid
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.PP
.B runuid
itself needs root privilege to run.
.SH OPTIONS
.TP
.B \-g group
Group.
Normally
.B runuid
sets the base group permission corresponding to the group ID of the
.IR account .
The
.B \-g
option may be used to specify a different base group permission.
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-S grplist
Supplemental (listed).
Normally
.B runuid
sets only a single group permission corresponding to the group ID of the
.IR account ,
or as specified with the
.B \-g
option.
The
.B \-S
option will additionally set supplemental group permissions
as given in the
.I grplist
argument,
a colon-delimited list of one or more arbitrary group names as defined in 
.IR /etc/group .
The
.B \-S
option and the
.B \-s
option are mutually exclusive.
.TP
.B \-s
Supplemental (/etc/group).
Normally
.B runuid
sets only a single group permission corresponding to the group ID of the
.IR account ,
or as specified with the
.B \-g
option.
The
.B \-s
option will additionally set all supplemental group permissions
defined for the
.I account
in
.I /etc/group
as described in
.BR initgroups (3).
The
.B \-s
option and the
.B \-S
option are mutually exclusive.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH EXIT STATUS
.B runuid
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runuid
itself.
.TP
100
.B runuid
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runuid
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runuid
failed due to some system or resource error.
In this case,
.B runuid
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlimit (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR initgroups (3),
.BR setgroups (2)
.\" EOF
